home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / etc / Fmt.man < prev    next >
Text File  |  1990-05-07  |  9KB  |  265 lines
  1. '\" Copyright 1989 Regents of the University of California
  2. '\" Permission to use, copy, modify, and distribute this
  3. '\" documentation for any purpose and without fee is hereby
  4. '\" granted, provided that this notice appears in all copies.
  5. '\" The University of California makes no representations about
  6. '\" the suitability of this material for any purpose.  It is
  7. '\" provided "as is" without express or implied warranty.
  8. '\" 
  9. '\" $Header: /sprite/src/lib/c/etc/RCS/Fmt.man,v 1.3 90/05/07 11:58:35 jhh Exp $ SPRITE (Berkeley)
  10. '/" 
  11. .so \*(]ltmac.sprite
  12. .HS Fmt lib
  13. .BS
  14. '\" Note:  do not modify the .SH NAME line immediately below!
  15. .SH NAME
  16. Fmt_Convert \- Package for converting data from one byte-order/alignment
  17. format to another. 
  18. .SH SYNOPSIS
  19. .nf
  20. \fB#include <fmt.h>\fR
  21. .sp
  22. int
  23. .br
  24. \fBFmt_Convert\fR(\fIcontents, inFormat, inSizePtr, inBuffer, outFormat, outSizePtr, outBuffer\fP)
  25. .sp
  26. int
  27. .br
  28. \fBFmt_Size\fR(\fIcontents, inFormat, inSizePtr, outFormat, outSizePtr\fR)
  29. .SH ARGUMENTS
  30. .AS Fmt_Format outSizePtr
  31. .AP char *contents in
  32. String describing contents of \fIinBuffer\fR (see below).
  33. .AP Fmt_Format inFormat in
  34. Byte-order/alignment format of data in \fIinBuffer\fR.
  35. .AP int *inSizePtr in/out
  36. Points to size of \fIinBuffer\fR.  Upon return \fI*inSizePtr\fR is
  37. the number of
  38. bytes actually used.
  39. .AP char *inBuffer in
  40. Data to be converted.
  41. .AP Fmt_Format outFormat in
  42. Byte-order/alignment format of data in \fIoutBuffer\fR.
  43. .AP int *outSizePtr in/out
  44. Points to size of \fIoutBuffer\fR.  Upon return \fI*outSizePtr\fR contains 
  45. the number of
  46. bytes actually used. For \fBFmt_Size\fR this is strictly an out parameter.
  47. .AP char *outBuffer in
  48. Converted data.
  49. .BE
  50.  
  51. .SH DESCRIPTION
  52. .PP
  53. \fBFmt_Convert\fR converts data between different 
  54. byte-order/alignment formats. Typically this is done between different
  55. machine types, but it can be used to convert between two compilers that
  56. align data differently.
  57. \fIInFormat\fR specifies the byte-order/alignment format of the 
  58. data in \fIinBuffer\fR,
  59. and \fIoutFormat\fR specifies the byte-order/alignment format of the data 
  60. in \fIoutBuffer\fR after the conversion.
  61. The data to be converted is read from \fIinBuffer\fR and the converted data is
  62. written to \fIoutBuffer\fR.
  63. The parameter \fIinSizePtr\fR points to the size of the input buffer. 
  64. When \fBFmt_Convert\fR returns
  65. \fI*inSizePtr\fR contains the number of bytes that were actually used.
  66. It is possible for less than the entire buffer to be converted depending
  67. upon the \fIcontents\fR string. 
  68. See below for more details on \fIcontents\fR.
  69. The parameter \fIoutSizePtr\fR points to the size of the output buffer. 
  70. When \fBFmt_Convert\fR returns \fI*outSizePtr\fR contains the
  71. number of bytes actually used. 
  72. .PP
  73. \fBFmt_Size\fR computes the minimum size output buffer needed converting
  74. the data at described by the \fIcontents\fR string
  75. The result is returned in \fI*outSizePtr\fR.
  76. This size can then be passed to \fBFmt_Convert\fR (assuming that the format
  77. and contents parameters remain the same).
  78.  
  79. The legal values for the format parameters are defined in fmt.h.
  80. They are as follows:
  81. .IP "\fBFMT_68K_FORMAT\fR"
  82. The byte-order/alignment format of code compiled by Gcc for 
  83. Motorola 680x0 machines.
  84. Treating an integer as an array of 4 bytes (char buf[4]), buf[0] contains
  85. the most significant byte.  
  86. Halfwords, words and doublewords are aligned on even 
  87. boundaries.  
  88. The alignment of structures and unions equals the most restrictive alignment
  89. of one of their members, such that they are at least aligned on 
  90. an even
  91. boundary.
  92. The size of structures and unions is a multiple of their alignment.
  93. .IP "\fBFMT_VAX_FORMAT\fR"
  94. The byte-order/alignment format of the Vax.
  95. Treating an integer as an array of 4 bytes (char buf[4]), buf[0] contains
  96. the least significant byte.  
  97. Halfwords are aligned on even boundaries. 
  98. Words and doublewords are aligned on word 
  99. boundaries.  
  100. The alignment of structures and unions equals the most restrictive alignment
  101. of one of their members.
  102. The size of structures and unions is a multiple of their alignment.
  103. .IP "\fBFMT_SPUR_FORMAT\fR"
  104. The byte-order/alignment format of code compiled by Gcc for the Spur.
  105. Treating an integer as an array of 4 bytes (char buf[4]), buf[0] contains
  106. the least significant byte.
  107. Halfwords are aligned on even boundaries, words are aligned on quad boundaries,
  108. and doublewords are aligned on oct boundaries.
  109. The alignment of structures and unions equals the most restrictive alignment
  110. of one of their members, such that they are at least aligned on 
  111. a quad
  112. boundary.
  113. The size of structures and unions is a multiple of their alignment.
  114. .IP "\fBFMT_SPARC_FORMAT\fR"
  115. The byte-order/alignment format of code compiled by the SunOS compiler
  116. for the Sparc architecture.
  117. Treating an integer as an array of 4 bytes (char buf[4]), buf[0] contains
  118. the 
  119. most
  120. significant byte.
  121. Halfwords are aligned on even boundaries, words are aligned on quad boundaries,
  122. and doublewords are aligned on oct boundaries.
  123. The alignment of structures and unions equals the most restrictive alignment
  124. of one of their members.
  125. The size of structures and unions is a multiple of their alignment.
  126. .IP "\fBFMT_MIPS_FORMAT\fR"
  127. The byte-order/alignment format of code compiled by the Ultrix compiler
  128. for the Mips (DecStation3100) architecture.
  129. Treating an integer as an array of 4 bytes (char buf[4]), buf[0] contains
  130. the 
  131. least
  132. significant byte.
  133. Halfwords are aligned on even boundaries, words are aligned on quad boundaries,
  134. and doublewords are aligned on oct boundaries.
  135. The alignment of structures and unions equals the most restrictive alignment
  136. of one of their members.
  137. The size of structures and unions is a multiple of their alignment.
  138. .VS
  139. .IP "\fBFMT_MY_FORMAT\fR"
  140. This format is set to the
  141. format of the machine on which the code is running.
  142. This relieves the program that is using the \fBFmt\fR package
  143. from having to
  144. decide with format is appropriate for a particular machine.
  145. .VE
  146. .PP
  147. The \fIcontents\fR parameter is used to describe the data types that comprise
  148. the input buffer. The buffer can contain bytes, halfwords (2 bytes),
  149. words (4 bytes), doublewords (8 bytes), structures, and unions.
  150. These data types are represented in the contents string using the 
  151. following characters.
  152. .IP \fBb\fR
  153. One byte.
  154. .IP \fBh\fR
  155. One halfword (2 bytes).
  156. .IP \fBw\fR
  157. One word (4 bytes).
  158. .IP \fBd\fR
  159. One double word (8 bytes).
  160. .IP \fB{\fR
  161. The start of a structure.
  162. .IP \fB}\fR
  163. The end of a structure.
  164. .IP \fB(\fR
  165. The start of a union. The '\fB(\fR' must be followed by a discriminant that 
  166. indicates which of the components of the union is to be converted.
  167. The discriminant is a decimal number that gives the index of the component,
  168. starting at 0.
  169. .IP \fB)\fR
  170. The end of a union.
  171. .IP \fB0\fR-\fB9\fR*
  172. A decimal number following a data type (byte, halfword, word, doubleword,
  173. structure, or union) indicates that the data type is repeated the
  174. given number of times. For instance, the string "w5" means that the 
  175. input contains 5 consecutive words. There is an ambiguity that arises
  176. when describing the contents of a union. "w5" can either refer to one
  177. component of 5 words, or to 5 components of one word each. 
  178. The abiguity is resolved by having "w5" refer to one component of 5 words,
  179. and "wwwww" refer to 5 components of one word. 
  180. Similarly, "w*" refers to one component (see next paragraph for description
  181. of the '*' character).
  182. .IP \fB*\fR
  183. A '\fB*\fR' means 1 or more repetitions of the previous data type. The number of
  184. repetitions is determined by the amount of data remaining in the input
  185. buffer. Care must be taken if the '\fB*\fR' character is anything but the
  186. last character in the string. Certain formats place constraints on the
  187. sizes of unions and structures that may cause the '\fB*\fR' character to
  188. give unwanted results. For example, consider a structure
  189. consisting of a word followed by a byte that is defined as "{wb*}".
  190. In the Spur format "b*" will refer to 4 bytes, while in the 68K format
  191. it will refer to 2 bytes.
  192.  
  193. .PP
  194. The following are examples of input data types and content strings.
  195. .sp
  196. \fIData\fR:
  197. .sp
  198.     int    foo[5];
  199. .sp
  200. \fIContent string\fR:
  201. .sp
  202.     "w5" or "w*" or "wwwww" 
  203. .sp
  204. \fIData\fR:
  205. .sp
  206. .DS
  207. .ta 1c 2c 4c 5c 6c
  208.     struct    flea    {
  209.         char        mite;
  210.         int        spider;
  211.         int        worm;
  212.         short        moth;
  213.         short        mosquito;
  214.         short        beetle;
  215.         int        fly[5];
  216.         char        gnat[50];
  217.     };
  218. .DE
  219. .sp
  220. \fIContent string\fR:
  221. .sp
  222. "{bwwh3w5b*}" 
  223. .sp
  224. \fIData\fR:
  225. .sp
  226. .DS
  227. .ta 1c 2c 5c 7c 9c
  228.     struct  foo    {
  229.         char    bar;
  230.         int    baz;
  231.         union {
  232.             short    quux;
  233.             double     cow;
  234.         } dog[6];
  235.     };
  236. .DE
  237. .sp
  238. \fIContent string\fR:
  239. .sp
  240.     "{bw(0hd)6}" or "{bw(0hd)*}"  if "quux" is the component of "dog" to be 
  241. converted, 
  242. .br
  243. or,
  244. .br
  245.     "{bw(1hd)6}" or "{bw(1hd)*}" if "cow" is the component of "dog" to be
  246. converted.
  247.  
  248. .SH "RETURN VALUES"
  249. .PP
  250. The following return codes are defined in fmt.h:
  251. .IP "\fBFMT_OK\fR (0)"
  252. Procedure completed properly
  253. .IP "\fBFMT_CONTENT_ERROR\fR"
  254. The \fIcontents\fR parameter contained an error.
  255. .IP "\fBFMT_INPUT_TOO_SMALL\fR"
  256. The input buffer was smaller than indicated by \fIcontents\fR.
  257. .IP "\fBFMT_OUTPUT_TOO_SMALL\fR"
  258. The output buffer was too small to hold the converted data. This is only
  259. returned by \fBFmt_Convert\fR.
  260. .IP "\fBFMT_ILLEGAL_FORMAT\fR"
  261. One of the format parameters was illegal.
  262. .SH KEYWORDS
  263. byte-order, byte-swap, alignment, data conversion
  264.  
  265.